<!DOCTYPE html>
<html>
    <head>

        <link rel="canonical" href="http://www.jointjs.com/" />
        <meta name="description" content="Create interactive diagrams in JavaScript easily. JointJS plugins for ERD, Org chart, FSA, UML, PN, DEVS, LDM diagrams are ready to use." />
        <meta name="keywords" content="JointJS, JavaScript, diagrams, diagramming library, UML, charts" />

        <link href="http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,700" rel="stylesheet" type="text/css" />
        <link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet">

        <link rel="stylesheet" href="css/tutorial.css" />
        <link rel="stylesheet" href="../node_modules/prismjs/themes/prism.css">


        <!-- Dependencies: -->
        <script src="../node_modules/jquery/dist/jquery.js"></script>
        <script src="../node_modules/lodash/lodash.js"></script>
        <script src="../node_modules/backbone/backbone.js"></script>


        <link rel="stylesheet" type="text/css" href="../build/joint.min.css" />
        <script type="text/javascript" src="../build/joint.min.js"></script>

        <title>JointJS - JavaScript diagramming library - Getting started.</title>

    </head>
    <body class="language-javascript tutorial-page">

        <script>
            SVGElement.prototype.getTransformToElement = SVGElement.prototype.getTransformToElement || function (toElement) {
                return toElement.getScreenCTM().inverse().multiply(this.getScreenCTM());
            };
        </script>

        <div id="ports" class="tutorial">

            <h2>Working with Ports</h2>

            <p>Many diagramming applications deal with elements with ports. Ports are usually displayed
                as circles inside diagram elements and are used not only as "sticky" points for connected links but they
                also further structure the linking information. It is common that certain elements have lists of input and
                output ports.
                A link might then point not to the element as a whole but to a certain port instead.</p>

            <p>JointJS has a built-in support for <a href="#create" target="_self">elements with ports</a>, <a href="#link" target="_self">linking between
                    ports</a> and a facility
                for <a href="#restrict" target="_self">defining what connections are allowed</a> and what not. This is useful if you, for
                example, want to
                restrict linking in between input ports, or output ports or between a certain port of an element A and a
                certain
                port of an element B. This tutorial shows you how you can do all that.</p>

            <h3 id="create">Creating elements with ports</h3>

            <p>The easiest way to start with elements with ports is using the <code>joint.shapes.devs</code> plugin. Search
                for <code>joint.shapes.devs.js</code>
                file. This
                plugin defines one important shape, the <code>joint.shapes.devs.Model</code>*. You can just instantiate that
                shape and
                pass the <code>inPorts</code> and <code>outPorts</code> arrays as parameters. You can further set the
                coloring of the ports
                and label for your element as you can see in the example below. Moreover, JointJS takes care of preparing
                the view and the magnets** for
                UI interaction. That's why you can already click and drag a port and JointJS automatically creates a link
                coming out
                of that port.</p>

            <p>JointJS and the <code>joint.shapes.devs.Model</code> also makes it easy to change ports. Simply set the
                <code>inPorts</code>/<code>outPorts</code> arrays of your element:

            <pre><code>element.set('inPorts', ['newIn1', 'newIn2', 'newIn3']);
element.set('outPorts', ['newOut1', 'newOut2']);</code></pre>

            <p class="small">*<a href="http://en.wikipedia.org/wiki/DEVS" target="_blank">DEVS</a> is an abbreviation for Discrete EVent
                System specification and is a formalism for modeling
                and analyzing general systems. This formalism uses two types of models (Atomic and Coupled) both having a
                set of input and output ports.</p>

            <p class="small">**Magnets in JointJS are SVG sub-elements that serve as sticky points for links. If you use the
                <code>joint.shapes.devs</code> plugin,
                you don't have to define your magnets yourself, instead the <code>joint.shapes.devs.Model</code> shape does
                it for you.</p>


            <div id="paper-create"></div>
            <script type="text/javascript" src="js/ports-create.js"></script>
            <pre data-src="js/ports-create.js" style="height: 440px"></pre>

            <h3 id="link">Linking elements with ports</h3>

            <p>Now when you have your elements with ports created, you can start observing what port is connected with
                a link to what other port. This is easy to do thanks to JointJS storing the information about ports in the
                link
                models themselves once the links are created via the UI. The following example shows you how you can get the
                linking
                information. Try to connect a port of one element to another port of another element.</p>

            <div id="paper-link"></div>
            <div id="paper-link-out"></div>
            <script type="text/javascript" src="js/ports-link.js"></script>
            <pre data-src="js/ports-link.js" style="height: 900px"></pre>

            <h3 id="restrict">Linking restrictions</h3>

            <p>Now you know how to create elements with ports and how to get the linking information. Another practical
                functionality related to elements with ports and their links is restricting certain connections. Say you
                want
                links to never start in input ports and never end in output ports. This is the most usual case. However,
                all kinds of restrictions are possible and application specific. JointJS doesn't limit you. Instead, it
                allows
                you to define a function that simply returns <code>true</code> if a connection between a source magnet of a
                source element
                and a target magnet of a target element is allowed, and <code>false</code> otherwise. If the connection is
                not
                allowed JointJS does not connect the magnets (and associated ports). Furthermore, you can mark certain
                magnets as
                <code>"passive"</code> in which case JointJS treats these magnets in a way that they can never become a
                source of a link.
                For further information, please see the list of options that you can pass to the
                <code>joint.dia.Paper</code> in the <a href="/docs/jointjs/v1.0/joint.html#dia.Paper" target="_top">API reference page</a>,
                especially the two related functions: <code>validateConnection()</code> and <code>validateMagnet()</code>.
            </p>

            <div id="paper-restrict"></div>
            <div id="paper-restrict-out"></div>
            <script type="text/javascript" src="js/ports-restrict.js"></script>
            <pre data-src="js/ports-restrict.js" style="height: 940px"></pre>

            <h3 id="snapLinks">Link snapping</h3>

            <p>To improve user experience little bit you might want to enable the link snapping. While the user is
                dragging a link, it searches for the closest port in the given radius. Once a suitable port is found (it
                meets requirements specified in validateConnection()) the link automatically connects to it. You can try
                this functionality in the example below.</p>

            <div class="paper" id="paper-link-snapping"></div>
            <script type="text/javascript" src="js/link-snapping.js"></script>

            <pre data-src="js/link-snapping.js" style="height: 800px"></pre>

            <h3 id="markAvailable">Marking available magnets</h3>

            <p>Another way how to make user's life easier can be to offer him all magnets he can connect to while he
                is dragging a link. To achieve this you have to enable <code>markAvailable</code> option on the
                paper and add some css rules into your stylesheet like in the example bellow.</p>

            <div class="paper" id="paper-mark-available"></div>
            <link rel="stylesheet" type="text/css" href="css/mark-available.css"/>
            <script type="text/javascript" src="js/mark-available.js"></script>

            <pre data-src="css/mark-available.css" style="height: 240px"></pre>
            <pre data-src="js/mark-available.js" style="height: 800px"></pre>
        </div>

        <script src="../node_modules/prismjs/prism.js"></script>

    </body>
</html>
